HybridMail Technical

AppendPdf XML attachment

The appendPdf attachment is used attach either XML files or PDF files to a letter. Appending XML files in the onPreSubmit phase can change the processing the letter will undergo during the OnSubmit phase. Appending PDF files in the OnSubmit phase adds them to the printed letter.

Schema

<mkzAttachment type="appendPdf"> 
	<onPreSubmit>
		<xmlPath>folder-where-XML-files-are-stored</xmlPath>
		<appendXml>XML-filename</appendXml>
	</onPreSubmit>
	<onSubmit>
		<pdfPath>folder-where-PDF-files-are-stored</pdfPath>
		<appendPdf [identifier="PDF-filename"] 
				   [mergeWithLetter="true|false" | useAsBackground="true|false" | insertRef="true|false"] 
				   [colour="true|false"] [first="true|false"] [map="true|false"] >PDF-filename</appendPdf>
		<mergePdf [identifier="PDF-filename"] position="nn" >PDF-filename</mergePdf>
		<insertPages position="nn" pages="mm"/>
		<deletePages position="nn" pages="mm"/>
		<reselectOutput>true</reselectOutput>
	</onSubmit>
</mkzAttachment>

The XML can be executed during the OnPreSubmit and OnSubmit phases.

The XML supports the following elements during OnPreSubmit. There can be multiple instances of any of these

<xmlPath> Specifies the folder where XML files are stored.

If this element is not specified, then every instance of <appendXml> will have to specify a fully-qualified pathname, not just a filename.

<appendXml>

Attaches the XML file as a letter attachment. There can be multiple instances of this element. These XML files will be processed as attachments when the onSubmit phase is executed.
N.B. XML attachments added by this method will be processed before any Template XML attachments.

The XML supports the following elements during OnSubmit. There can be multiple instances of any of these

<pdfPath> Specifies the folder where PDF files are stored.

If this element is not specified, then every instance of <appendPdf> will have to specify a fully-qualified pathname, not just a filename.

<appendPdf>

Attaches the PDF file as a letter attachment. There can be multiple instances of this element.

<appendPdf insertRef="reference">

If this attribute exists and is not empty, then the 'reference' will added to the letter instead of the physical PDF file. When the letter is finally printed, the reference will be used to insert a pre-printed attachment. This attribute is optional.

<appendPdf useAsBackground="true">

If this attribute exists and is set to 'true', then the PDF file specified will be used as the background for the parent letter instead of being appended to the end. This attribute is optional.

<appendPdf mergeWithLetter="true">

If this attribute exists and is set to 'true', then the PDF file specified will appended directly to the parent letter instead of being treated as an attachment. This attribute is optional.

N.B. This approach is not the preferred way of adding attachments because it results in increased file sizes and consequently increased resource usage and slower processing. This method should be used only when an attachment needs to be ‘personalised’ to the recipient; e.g. if it is necessary to stamp the recipient’s name or account number on the attachment. A blank page may be inserted to ensure that the attachment always starts on an odd-numbered page.

<appendPdf colour="true">

If this attribute exists and is set to 'true', then the letter will be designated a 'colour' letter. This attribute is optional.

<appendPdf first="true">

If this attribute exists and is set to 'true', then the letter will be designated a 'first-class' letter. This attribute is optional.

<appendPdf map="true">

If this attribute exists and is set to 'true', then the attachment will be designated a 'map' rather than a informational attachment. This is used by electronic delivery to assign a different icon to the attachment. This attribute is optional.

<mergePdf>

Merges the named PDF file with the letter file at the specified position. There can be multiple instances of this element.

<mergePdf position="nn">

This attribute specifies the position at which the PDF file will be inserted into the letter file. This is generally synonymous with 'the page number after which the PDF file will be inserted'. However position '0' can be used to indicate the start of the letter. Use positive numbers to indicate the ‘nth’ page from the start of the letter and negative numbers for the ‘nth’ page from the end of the letter. E.g.

position="1" insert after the first page
position="2" insert after the second page
position="-1" insert after the last page
position="-3" insert after the third last page

N.B. Unlike <appendPdf>, <mergePdf> does not add blank pages to try and preserve alignment to an odd-numbered page.

<insertPages>

Inserts blank pages into the letter file at the specified position. There can be multiple instances of this element.

<insertPages position="nn" pages="mm">

These attributes specifies the page number after which the blank pages will be inserted and the number of pages to insert. See <mergePdf> to specify the page number after which the pages will be inserted. 'mm' specifies the number of pages to insert. Both these attributes are mandatory.

<deletePages>

Deletes pages from the letter file starting at, and including, the specified position. There can be multiple instances of this element.

<deletePages position="nn" pages="mm">

These attributes specifies the page number which will be deleted and the number of pages to delete. See <mergePdf> to specify the first page which will be deleted. 'mm' specifies the number of pages to delete. Both these attributes are mandatory.

<reselectOutput>true</reselectOutput>

Force Hybridmail to reselect the most appropriate output queue for this letter now that it has been modified.

An optional element, but should really be considered mandatory if any of the above elements change either the colour or first properties of the parent letter, or the number of sheets it requires. Setting this to true causes the auto-assigned output queue to be recalculated based on changes that may have been made to the letter properties, or to the number of sheets that the letter now requires as a result of added PDF files.

Examples

If the scan area contains 'Maidstone', append 'Site-map.pdf' as an attachment to the letter and set the letter to colour.

<if letterValue="address" contains="maidstone">
	<appendPdf colour="true" >Site-map.pdf</appendPdf>
</if>

If the recipient addresss contains 'Imperial', insert 'clinicMapA.pdf' netween pages 1 and 2.

<if letterValue="address" contains="Imperial" >
	<mergePdf position="1" >clinicMapA.pdf</mergePdf>
</if>

If the scan area contains 'cover-req', insert 'Coverletter.pdf' at the start of the letter.

<if scan="0,0,100,20" contains="cover-req" >
	<mergePdf position="0" >Coverletter.pdf</mergePdf>
</if>

Delete the last page of the letter, if it is blank.

<if scan="0,0,210,297" page="-1" isEmpty="true" >
	<deletePages position="-1" pages="1"/>
</if>